home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / MENU_UTL / PULL70B / PULLREF.DOC < prev    next >
Text File  |  1993-09-24  |  75KB  |  1,688 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.                            MULTI-LEVEL PULL-DOWN MENUS
  20.                                  REFERENCE GUIDE
  21.  
  22.                                   Version 7.0b
  23.                                September 24, 1993
  24.  
  25.  
  26.                Copyright (C) 1988,1993 Eagle Performance Software
  27.                               All Rights Reserved.
  28.  
  29.  
  30.  
  31.                                _______                     
  32.                           ____|__     |               (tm) 
  33.                        --|       |    |------------------- 
  34.                          |   ____|__  |  Association of    
  35.                          |  |       |_|  Shareware         
  36.                          |__|   o   |    Professionals     
  37.                        -----|   |   |--------------------- 
  38.                             |___|___|    MEMBER            
  39.  
  40.  
  41.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  42.  
  43.  
  44.  
  45.                        T A B L E   O F   C O N T E N T S
  46.  
  47.         1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 3
  48.              Purpose . . . . . . . . . . . . . . . . . . . . . . . 3
  49.              Fill-in-the-Blank . . . . . . . . . . . . . . . . . . 3
  50.  
  51.         2. PROCEDURES AND FUNCTIONS  . . . . . . . . . . . . . . . 4
  52.              CheckForPop . . . . . . . . . . . . . . . . . . . . . 4
  53.              CheckForPullDown  . . . . . . . . . . . . . . . . . . 4
  54.              CheckGlobalKeys . . . . . . . . . . . . . . . . . . . 4
  55.              DisplayFields . . . . . . . . . . . . . . . . . . . . 4
  56.              Enter . . . . . . . . . . . . . . . . . . . . . . . . 5
  57.              EnterSeq  . . . . . . . . . . . . . . . . . . . . . . 5
  58.              GetOverrideStats  . . . . . . . . . . . . . . . . . . 5
  59.              GetUserPullStats  . . . . . . . . . . . . . . . . . . 5
  60.              GotoKeyDispatcher . . . . . . . . . . . . . . . . . . 5
  61.              HelpKeyPressed  . . . . . . . . . . . . . . . . . . . 6
  62.              HiLiteRow . . . . . . . . . . . . . . . . . . . . . . 6
  63.              InitPull  . . . . . . . . . . . . . . . . . . . . . . 6
  64.              Popped  . . . . . . . . . . . . . . . . . . . . . . . 6
  65.              PullDirectory . . . . . . . . . . . . . . . . . . . . 7
  66.              PullHelpWndw  . . . . . . . . . . . . . . . . . . . . 7
  67.              ReadKbd . . . . . . . . . . . . . . . . . . . . . . . 7
  68.              SetCmdSeq . . . . . . . . . . . . . . . . . . . . . . 7
  69.              ShowErrMsg  . . . . . . . . . . . . . . . . . . . . . 7
  70.              ShowMsg . . . . . . . . . . . . . . . . . . . . . . . 8
  71.              ShowTopLine . . . . . . . . . . . . . . . . . . . . . 8
  72.              StrJL . . . . . . . . . . . . . . . . . . . . . . . . 8
  73.              StrJR . . . . . . . . . . . . . . . . . . . . . . . . 8
  74.              TopKeyPressed . . . . . . . . . . . . . . . . . . . . 9
  75.              TurnArrows  . . . . . . . . . . . . . . . . . . . . . 9
  76.              WorkWndw  . . . . . . . . . . . . . . . . . . . . . . 9
  77.  
  78.         3. DATA STRUCTURE  . . . . . . . . . . . . . . . . . . . . 10
  79.              Configuration Constants . . . . . . . . . . . . . . . 10
  80.              Main Menu Declarations  . . . . . . . . . . . . . . . 11
  81.              Submenu Declarations  . . . . . . . . . . . . . . . . 17
  82.              Message Line Declarations . . . . . . . . . . . . . . 18
  83.              Help Window Declarations  . . . . . . . . . . . . . . 19
  84.              Data Window/Entry Declarations  . . . . . . . . . . . 20
  85.  
  86.         APPENDIX A:  MEMORY ALLOCATION . . . . . . . . . . . . . . 26
  87.              Global vs. Dynamic  . . . . . . . . . . . . . . . . . 26
  88.              Global Memory . . . . . . . . . . . . . . . . . . . . 26
  89.              Dynamic Memory  . . . . . . . . . . . . . . . . . . . 26
  90.              Code Size . . . . . . . . . . . . . . . . . . . . . . 27
  91.  
  92.         APPENDIX B:  ERROR MESSAGES  . . . . . . . . . . . . . . . 28
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.                                        2
  102.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  103.  
  104.  
  105.    1.  I N T R O D U C T I O N
  106.  
  107.  
  108.    PURPOSE
  109.  
  110.    This document is a technical reference manual describing each routine and 
  111.    variable in detail in a format similar to the BP7 manual.  The routines are 
  112.    described in alphabetical order.  Since this manual is on disk, you can 
  113.    find your interest easily with any search utility.
  114.  
  115.    Application - Because PULL uses QWIK and WNDW, all routines will perform in 
  116.    the following applications:
  117.  
  118.      . All video text modes - 0, 1, 2, 3 and 7.
  119.      . Any column mode - 40, 80, or variable.
  120.      . For IBM PC, XT, AT, PCjr, PC convertible, all PS/2 models, 3270 PC, and 
  121.        compatibles.
  122.      . With MDA, CGA, EGA, MCGA, VGA, 8214/A, all Hercules video cards.
  123.      . Perform routines in both absolute and window-relative coordinates.
  124.      . Works in DOS and DPMI platforms.
  125.  
  126.    Please note that the demonstration files are set to work on an 80 column 
  127.    mode on video page 0 in a non-multi-tasking environment.  However, these 
  128.    can be changed with the source code.
  129.  
  130.  
  131.    FILL-IN-THE-BLANK
  132.  
  133.    Since most of PULL is based on the fill-in-the-blank concept for records, 
  134.    there are only a few procedures and functions that you would need to know 
  135.    about data entries and specialized programming of user windows.  Most of 
  136.    your interest will probably be in the Data Structure section that follows 
  137.    later, so you know which "blanks" you can fill.
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.    Chapter 1, Introduction                                             Page 3
  163.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  164.  
  165.  
  166.    2.  P R O C E D U R E S   A N D   F U N C T I O N S
  167.  
  168.    In this section, a detailed description is provided for each procedure and 
  169.    function.
  170.  
  171.  
  172.    ---------------------------------------------------------------------------
  173.    CheckForPop procedure                                                  Pull
  174.    ---------------------------------------------------------------------------
  175.    Function       Sets Pop true if menu(s) need to be removed.
  176.    Declaration    CheckForPop
  177.    Remarks        This procedure is primarily used in user windows that to 
  178.                   interface with the pull-down menus.  It analyzes the current 
  179.                   status of the menu control flags to see if one or more menus 
  180.                   need to be removed.
  181.    See also       CheckForPullDown
  182.    Example        See the User Window section in PULL70B.DOC.
  183.  
  184.    ---------------------------------------------------------------------------
  185.    CheckForPullDown procedure                                             Pull
  186.    ---------------------------------------------------------------------------
  187.    Function       Displays help message, reads keyboard input, and permits 
  188.                   background processing while keyboard is idle.
  189.    Declaration    CheckForPullDown (MsgLineNum: byte)
  190.    Remarks        This procedure is primarily used in user windows that to 
  191.                   interface with the pull-down menus.  It analyzes the current 
  192.                   status of the menu control flags to see if it has reached 
  193.                   its destination menu/window.  If WaitForKbd is false when 
  194.                   entering this procedure, it will assume that Key and ExtKey 
  195.                   are set correctly and not wait for the keyboard input for 
  196.                   just one pass.  ReadKbd and KbdIdle are subroutines.
  197.    Example        See the User Window section in PULL70B.DOC.
  198.    See also       CheckForPop, KbdIdle, ReadKbd
  199.  
  200.    ---------------------------------------------------------------------------
  201.    CheckGlobalKeys procedure                                          PullStat
  202.    ---------------------------------------------------------------------------
  203.    Function       Provides a case of global keystrokes to access any part 
  204.                   of the program at any time.
  205.    Declaration    Called indirectly by PULL.
  206.    Remarks        Global keys can be any extended key.  The contents are 
  207.                   optional, but the procedure must exist.  You must include 
  208.                   PullStat in at least on USES statement in the program even 
  209.                   though it can compile without it.
  210.    See also       GetUserPullStats, GetOverrideStats
  211.  
  212.    ---------------------------------------------------------------------------
  213.    DisplayFields procedure                                                Pull
  214.    ---------------------------------------------------------------------------
  215.    Function       Displays the contents of a sequence of data entry fields 
  216.                   given the first and last record numbers.
  217.    Declaration    DisplayFields (First,Last: word)
  218.    Remarks        Fields are displayed in window-relative coordinates.
  219.    See also       Enter, EnterSeq
  220.  
  221.  
  222.  
  223.    Chapter 2, Procedures and Functions                                 Page 4
  224.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  225.  
  226.  
  227.    ---------------------------------------------------------------------------
  228.    Enter procedure                                                        Pull
  229.    ---------------------------------------------------------------------------
  230.    Function       Edits a field for a single data entry given the Data Entry 
  231.                   record.
  232.    Declaration    Enter (RecNum: word);
  233.    Remarks        This procedure is used if you want to customize your own 
  234.                   sequence of entry.  RecNum is the record number of the data 
  235.                   entry.  This procedure only shows the string being edited 
  236.                   for input.  For output display, use DisplayFields.
  237.    See also       DisplayFields, EnterSeq
  238.  
  239.    ---------------------------------------------------------------------------
  240.    EnterSeq procedure                                                     Pull
  241.    ---------------------------------------------------------------------------
  242.    Function       Edits a sequence of fields for data entry given the Data 
  243.                   Entry records.
  244.    Declaration    EnterSeq (First,Last: word; VAR Start: word);
  245.    Remarks        This procedure handles full editing of a sequence of data 
  246.                   entries handled by smart HiLite algorithms.  The sequence of 
  247.                   entry is the order of DataEntryNames in PULLDATA.PAS.  
  248.                   First/Last are the first and last record numbers in the 
  249.                   sequence.  Start is where you want the HiLite to start, and 
  250.                   keeps up with the current record.  Use DisplayFields once 
  251.                   before editing.
  252.    See also       DisplayFields, Enter
  253.  
  254.    ---------------------------------------------------------------------------
  255.    GetOverrideStats procedure                                         PullStat
  256.    ---------------------------------------------------------------------------
  257.    Function       Overrides any default configurations set by GetUserPullStats 
  258.                   and InitPull.
  259.    Declaration    Called indirectly by PULL.
  260.    Remarks        If you have any exceptions for your menu records, place your 
  261.                   assignments in this procedure.  The contents are optional, 
  262.                   but the procedure must exist.  You must include PullStat in 
  263.                   at least one USES statement in the program even though it 
  264.                   can compile without it.
  265.    See also       CheckGlobalKeys, GetUserPullStats
  266.  
  267.    ---------------------------------------------------------------------------
  268.    GetUserPullStats procedure                                         PullStat
  269.    ---------------------------------------------------------------------------
  270.    Function       Initializes all menus, windows and message lines for the 
  271.                   pull-down environment.
  272.    Declaration    Called indirectly by PULL.
  273.    Remarks        You must include the PullStat in at least one USES statement 
  274.                   in the program even though it can compile without it.
  275.    See also       CheckGlobalKeys, GetOverrideStats
  276.  
  277.    ---------------------------------------------------------------------------
  278.    GotoKeyDispatcher procedure                                            Pull
  279.    ---------------------------------------------------------------------------
  280.    Function       Turns control over to PULL.
  281.    Declaration    GotoKeyDispatcher
  282.  
  283.  
  284.    Chapter 2, Procedures and Functions                                 Page 5
  285.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  286.  
  287.  
  288.    Remarks        This procedure is called by your main program after all the 
  289.                   data record have been initialized.
  290.    Example        See PULLDEMO.PAS.
  291.  
  292.    ---------------------------------------------------------------------------
  293.    HelpKeyPressed function                                                Pull
  294.    ---------------------------------------------------------------------------
  295.    Function       Trivial function returns true if the context-sensitive help 
  296.                   key has been pressed.
  297.    Declaration    HelpKeyPressed
  298.    Result type    boolean
  299.    Remarks        PULL is currently assigned the F1 key for the help window.
  300.    See also       TopKeyPressed, PullHelpWndw
  301.  
  302.    ---------------------------------------------------------------------------
  303.    HiLiteRow procedure                                                    Pull
  304.    ---------------------------------------------------------------------------
  305.    Function       Highlights a line in a menu.
  306.    Declaration    HiLiteRow (Row: byte; Attr: integer)
  307.    Remarks        This procedure can be used in any user menu to show the 
  308.                   HiLite bar by simply changing the attribute.  Row is a 
  309.                   window-relative row and Attr is the attribute for the 
  310.                   HiLite.
  311.  
  312.    ---------------------------------------------------------------------------
  313.    InitPull procedure                                                     Pull
  314.    ---------------------------------------------------------------------------
  315.    Function       Initializes WNDW and PULL records.
  316.    Declaration    InitPull (Attr: integer; ClearScr: boolean)
  317.    Remarks        Attr is the attribute of Window0 and is also assigned to the 
  318.                   global variable InitAttr.  If ClearScr is true, it will 
  319.                   clear the screen which is not necessary for PermMode 
  320.                   windows.  This procedure is required and is only used once.
  321.  
  322.    ---------------------------------------------------------------------------
  323.    Popped function                                                        Pull
  324.    ---------------------------------------------------------------------------
  325.    Function       Used to detect if all menus have all been removed before 
  326.                   executing menu procedures.
  327.    Declaration    Popped
  328.    Result type    boolean
  329.    Remarks        This function is used in procedures called by the menu 
  330.                   ProcPtr.  PULL executes the ProcPtr procedure twice when 
  331.                   Popped is used.  It sets several flags for you including 
  332.                   PopAndProcess.  The first time Popped is tested it returns 
  333.                   false and sets the appropriate flags.  When the menus are 
  334.                   removed and ProcPtr is executed again, Popped will be true.  
  335.                   This allows your statement to read like plain English.
  336.    Example        This far procedure is called by a ProcPtr in a menu:
  337.  
  338.                     procedure MyProc;
  339.                     begin
  340.                       if Popped then DoMyProc;
  341.                     end;
  342.  
  343.  
  344.  
  345.    Chapter 2, Procedures and Functions                                 Page 6
  346.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  347.  
  348.  
  349.    ---------------------------------------------------------------------------
  350.    PullDirectory procedure                                             PullDir
  351.    ---------------------------------------------------------------------------
  352.    Function       Displays the contents of the current disk directory.
  353.    Declaration    PullDirectory (VAR NameToChange: FileNameStr;
  354.                                      NameToHiLite: FileNameStr);
  355.    Remarks        Pressing RETURN on the HiLited item will be assigned to 
  356.                   NameToChange.  If NameToHiLite is given, the menu will be 
  357.                   displayed initially with the HiLite centered in the menu on 
  358.                   NameToHiLite.  If NameToHiLite is null, the HiLite will just 
  359.                   be centered on the first page.
  360.    Example        See PULLSTAT.PAS for PULLDEMO.PAS.
  361.  
  362.    ---------------------------------------------------------------------------
  363.    PullHelpWndw procedure                                                 Pull
  364.    ---------------------------------------------------------------------------
  365.    Function       Displays a context-sensitive help window.
  366.    Declaration    PullHelpWindow (WndwNum: byte);
  367.    Remarks        This procedure can be used in any procedure where keyboard 
  368.                   input is tested.  WndwNum is the HelpWndw record number, but 
  369.                   using the ordinal value of HelpWndwNames is easier to use.
  370.    See also       HelpKeyPressed
  371.  
  372.    ---------------------------------------------------------------------------
  373.    ReadKbd procedure                                                      Pull
  374.    ---------------------------------------------------------------------------
  375.    Function       Reads keyboard input and permits background processing while 
  376.                   keyboard is idle.
  377.    Declaration    ReadKbd (VAR ExtKey: boolean; VAR Key: char);
  378.    Remarks        ExtKey is true if the key is extended.  Key is the character 
  379.                   of the key entered.  In addition, holding down the Alt key 
  380.                   will display the global key combination message.  Also, 
  381.                   while the keyboard is idle, the KbdIdle procedure is being 
  382.                   continually executed.
  383.    See also       CheckForPullDown, KbdIdle
  384.  
  385.    ---------------------------------------------------------------------------
  386.    SetCmdSeq procedure                                                    Pull
  387.    ---------------------------------------------------------------------------
  388.    Function       Sets PULL control flags to shortest path to the new menu.
  389.    Declaration    SetCmdSeq (NewCmdSeq: SeqStr)
  390.    Remarks        NewCmdSeq is the sequence of command letters pressed after 
  391.                   F10 to arrive at a new menu or window.  NewCmdSeq and the 
  392.                   current position, CmdSeq, are compared to create an new path 
  393.                   by setting MoreCmdSeq and PopLevels.
  394.  
  395.    ---------------------------------------------------------------------------
  396.    ShowErrMsg procedure                                                   Pull
  397.    ---------------------------------------------------------------------------
  398.    Function       Shows an error message on the message line.
  399.    Declaration    ShowErrMsg (ErrMsgNum: word);
  400.    Remarks        ErrMsgNum is the index of the ErrMsgLine to display.  It is 
  401.                   easier to use the ordinal value of ErrMsgNames to identify 
  402.                   the message to display.  This message is usually used by 
  403.                   data entry routines.  After pressing ESC to acknowledge the 
  404.  
  405.  
  406.    Chapter 2, Procedures and Functions                                 Page 7
  407.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  408.  
  409.  
  410.                   message, the original message is restored.
  411.    See also       ShowMsg
  412.    Example        Show the error message line named MyErrMsg:
  413.  
  414.                     ShowErrMsg (ord(MyErrMsg));
  415.  
  416.    ---------------------------------------------------------------------------
  417.    ShowMsg procedure                                                      Pull
  418.    ---------------------------------------------------------------------------
  419.    Function       Shows a message on the message line.
  420.    Declaration    ShowMsg (MsgNum: byte)
  421.    Remarks        MsgNum is the index of the MsgLine to display.  It is easier 
  422.                   to use the ordinal value of MsgLineNames to identify the 
  423.                   message to display.
  424.    See also       CheckForPullDown, ShowErrMsg
  425.    Example        Show the message line named MyMsg:
  426.  
  427.                     ShowMsg (ord(MyMsg));
  428.  
  429.  
  430.    ---------------------------------------------------------------------------
  431.    ShowTopLine procedure                                                  Pull
  432.    ---------------------------------------------------------------------------
  433.    Function       Simply displays the unhighlighted Top Line Menu.
  434.    Declaration    ShowTopLine
  435.    Remarks        This procedure is used to initially display the Top Line 
  436.                   menu for the screen design in PULLWORK.PAS or PULLSHEL.PAS.  
  437.                   It writes the string TopLineStr to the screen which is 
  438.                   assembled by InitPull.
  439.  
  440.    ---------------------------------------------------------------------------
  441.    StrJL function                                                         Pull
  442.    ---------------------------------------------------------------------------
  443.    Function       Returns a string left justified in a field of spaces.
  444.    Declaration    StrJL (S: string; Field: byte)
  445.    Result type    string
  446.    Remarks        If Field is less than the length of the string, the string 
  447.                   is simply returned.  This duplicates the same routine in the 
  448.                   STRG unit of SpeedPack II.
  449.    See also       StrJR
  450.  
  451.    ---------------------------------------------------------------------------
  452.    StrJR function                                                         Pull
  453.    ---------------------------------------------------------------------------
  454.    Function       Returns a string right justified in a field of spaces.
  455.    Declaration    StrJR (S: string; Field: byte)
  456.    Result type    string
  457.    Remarks        If Field is less than the length of the string, the string 
  458.                   is simply returned.  This duplicates the same routine in the 
  459.                   STRG unit of SpeedPack II.
  460.    See also       StrJL
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.    Chapter 2, Procedures and Functions                                 Page 8
  468.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  469.  
  470.  
  471.    ---------------------------------------------------------------------------
  472.    TopKeyPressed function                                                 Pull
  473.    ---------------------------------------------------------------------------
  474.    Function       Trivial function returns true if the top line menu key has 
  475.                   been pressed.
  476.    Declaration    TopKeyPressed
  477.    Result type    boolean
  478.    Remarks        PULL is currently assigned the F10 key for the top line 
  479.                   menu.
  480.    See also       HelpKeyPressed
  481.  
  482.    ---------------------------------------------------------------------------
  483.    TurnArrows procedure                                                   Pull
  484.    ---------------------------------------------------------------------------
  485.    Function       Displays or removes arrows on the highlighted line of a 
  486.                   menu that pulls down a submenu or user window.
  487.    Declaration    TurnArrows (Switch: Toggle)
  488.    Remarks        This procedure is used primarily to interface with user 
  489.                   windows that require the submenu arrows to be turned on or 
  490.                   off.
  491.    Example        See the User Window section in PULL70B.DOC.
  492.  
  493.    ---------------------------------------------------------------------------
  494.    WorkWndw procedure                                                 PullWork
  495.    ---------------------------------------------------------------------------
  496.    Function       Provides a case of steps for the work window as the main 
  497.                   part of the program.
  498.    Declaration    Called indirectly by PULL.
  499.    Remarks        The contents are optional, but the procedure must exist.  
  500.                   You must include PullWork in the USES statement of the main 
  501.                   program even though it can compile without it.
  502.    Example        See PULLSHEL.PAS and PULLDEMO.PAS.
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.    Chapter 2, Procedures and Functions                                 Page 9
  529.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  530.  
  531.  
  532.    3.  D A T A   S T R U C T U R E
  533.  
  534.    This section will help describe the data structure of PULL and how it can 
  535.    be adjusted.  The variables in P70-VAR.INC are allocated according to the 
  536.    conditional directives and constants set at the beginning of the file.  
  537.    There are several basic variables, but if desired, there are additional 
  538.    variables for virtual windows and multiple video pages.  Please refer to 
  539.    the source code in P70-VAR.INC for the exact listing.
  540.  
  541.  
  542.    CONFIGURATION CONSTANTS
  543.  
  544.    These constants configure the size of the data structure.  If you have the 
  545.    complete source code, the constants can be trimmed to fit the requirements 
  546.    of your application program.  While developing the program, you can balloon 
  547.    these values so that PULL does not need to be recompiled every time the 
  548.    program expands.
  549.  
  550.      Constant          Value  Description
  551.      ----------------  -----  ------------------------------------------------
  552.      NumOfMainMenus    1-255  Sets the maximum number of main menu records to 
  553.                               be held in the heap.
  554.  
  555.      NumOfSubMenus     1-255  Sets the maximum number of submenu records to be 
  556.                               held in the heap.
  557.  
  558.      MaxMenuLines      1-253  Sets the maximum number of menu lines in each 
  559.                               menu record.
  560.  
  561.      MaxCharsPerLine   1-247  Sets the maximum number of characters per line 
  562.                               in all menu lines.  It also limits the size of 
  563.                               the title for the data windows.
  564.  
  565.      NumOfDataWndws    1-255  Sets the maximum number of data window records 
  566.                               to be held in the heap.
  567.  
  568.      NumOfDataEntries  1-255  Sets the maximum number of data entry records to 
  569.                               be held in the heap.
  570.  
  571.      DataStrSize       1-255  Sets the maximum number of characters that can 
  572.                               be entered in a data entry of any kind.
  573.  
  574.      NumOfHelpWndws    1-255  Sets the maximum number of help window records 
  575.                               to be held in global data.
  576.  
  577.      TotalHelpLines    1-255  Sets the maximum number of help lines in the 
  578.                               HelpLine array.  A greater number of lines can 
  579.                               be used if TP5 enumerated types are not used for 
  580.                               the index. 
  581.  
  582.      HelpCharsPerLine  1-241  Sets the maximum number of characters per line 
  583.                               in all help windows.  Remember this excludes the 
  584.                               two extra spaces between border and text.
  585.  
  586.      NumOfMsgLines     1-255  Sets the maximum number of message lines to be 
  587.  
  588.  
  589.    Chapter 3, Data Structure                                           Page 10
  590.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  591.  
  592.  
  593.                               allocated in the MsgLine array.
  594.  
  595.      CrtStrSize        1-255  Sets the maximum number of characters that can 
  596.                               appear on a CRT's width.
  597.  
  598.      NumOfErrMsgLines  1-up   Sets the maximum number of message lines to be 
  599.                               allocated in the ErrMsgLine array.
  600.  
  601.      ErrStrSize        1-255  Sets the maximum number of characters in a 
  602.                               single ErrStrLine message.  This is usually less 
  603.                               than CrtStrSize, but cannot be greater.
  604.  
  605.      MsgStrSize        1-255  Sets the maximum number of characters in a 
  606.                               single MsgStrLine message.  This can be up to 
  607.                               CrtStrSize plus an allowance for some '~' 
  608.                               characters for highlighting.
  609.  
  610.  
  611.    MAIN MENU DECLARATIONS
  612.  
  613.    The following types, variables and constants are used for primarily for the 
  614.    main menus.  The variables are described in the order of their appearance 
  615.    in the file P70-VAR.INC.
  616.  
  617.  
  618.    Types - These types are used to structure variables for the main menus:
  619.  
  620.      Type          Description
  621.      ------------  -----------------------------------------------------------
  622.      MenuModeType  This enumerated type gives a name for three different menu 
  623.                    modes.  Each mode controls how each line will interact with 
  624.                    the other lines.
  625.  
  626.                      Name            Description
  627.                      --------------  --------------------------------------
  628.                      ExecChoice      Executes the procedures indicated by 
  629.                                      ProcPtr and does not interact with the 
  630.                                      other menu lines.  This is the default.
  631.                      SingleChoice    Flags only the selected line in the menu 
  632.                                      and turns off all other flags.  If 
  633.                                      ProcPtr is not nil, it will also execute 
  634.                                      the procedure before flagging.
  635.                      MultipleChoice  Toggles the flag on any line in the menu.  
  636.                                      If ProcPtr is not nil, it will also 
  637.                                      execute the procedure before flagging.
  638.  
  639.      LineModeType  This enumerated type gives a name for seven different line 
  640.                    modes for any one line in the menu.
  641.  
  642.                      Name        Description
  643.                      ----------  ------------------------------------------
  644.                      Choice      Interacts with the rest of the menu 
  645.                                  according to the given menu mode.
  646.                      ExecOnly    Only executes ProcPtr and ignores flagging.
  647. |                    NoChoice    Disables line as a valid choice, but can be 
  648.  
  649.  
  650.    Chapter 3, Data Structure                                           Page 11
  651.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  652.  
  653.  
  654. |                                restored by replacing the original line mode.
  655.                      Comment     Places text on the line with a different 
  656.                                  attribute and passed by the highlight.
  657.                      Partition   Places a horizontal border through the menu 
  658.                                  and is passed by the highlight.
  659.                      ToDataWndw  Places a dot symbol on the line and pulls 
  660.                                  down a data entry window.
  661.                      ToSubMenu   Places a three-bar symbol on the line and 
  662.                                  pulls down a submenu.
  663.                      ToUserWndw  Places a three-bar symbol on the line and 
  664.                                  executes ProcPtr.
  665.  
  666.      ProcPtrType   This is the type established for procedure pointers and is 
  667.                    a generic pointer type.
  668.  
  669.      Toggle        This enumerated type is just a practical way of 
  670.                    understanding the source code to indicate the common binary 
  671.                    conditions of On/Off and Yes/No.
  672.  
  673.      CrtStrType    Combined with CrtStrSize, this type will limit the size of 
  674.                    strings needed to display data onto the screen.  It is 
  675.                    usually used for message lines.
  676.  
  677.      MsgStrType    Combined with MsgStrSize, this type will limit the size of 
  678.                    strings needed to display data on the Message line which 
  679.                    includes '~' characters for highlighted characters in the 
  680.                    message string.
  681.  
  682.      SeqStrType    This type is used for strings that keep a record of the 
  683.                    command sequence.  Since the sequence is not greater than 
  684.                    the number of windows on the screen at any one time, 
  685.                    Wndw.MaxWndw is used.
  686.  
  687.      MenuRec       This record is used to fully describe any menu.  Each field 
  688.                    is worth describing.
  689.  
  690.                      Title - For main menus, this name will appear on the Top 
  691.                      Line menu.
  692.  
  693.                      CmdLtrs - InitPull assigns the first letter of each menu 
  694.                      line to be its corresponding command letter.  This string 
  695.                      keeps these assignments in sequence so that the line 1 
  696.                      letter is position 1, line 2 is position 2, etc.
  697.  
  698.                      Line - This is the array of the actual text that will 
  699.                      appear on each menu line.  The default is ''.
  700.  
  701.                      LineMode - This array is the line mode corresponding to 
  702.                      each line.  The default is Choice.
  703.  
  704.                      Flagged - This array is the status of the boolean flag 
  705.                      corresponding to each line.  The default is false.
  706.  
  707.                      LinkNum - This array has the byte value of submenu or 
  708.                      data window names of records to be linked.  The default 
  709.  
  710.  
  711.    Chapter 3, Data Structure                                           Page 12
  712.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  713.  
  714.  
  715.                      is 0.
  716.  
  717.                      ProcPtr - This array has the pointers for executing far 
  718.                      procedures when the menu line is selected.  The default 
  719.                      is nil which executes nothing.
  720.  
  721.                      ParentDir - This is the linking direction assigned to the 
  722.                      parent menu of this menu (which would be a submenu).  For 
  723.                      main menus, this value is NoDir.
  724.  
  725.                      LinkDir - This is the linking direction assigned to all 
  726.                      submenus on this menu which is determined by InitPull.
  727.  
  728.                      MenuMode - This is the menu mode.
  729.  
  730.                      MenuLines - This is the number of lines contained in this 
  731.                      menu and is determined by InitPull.
  732.  
  733.                      NameCol - For main menus, this is the column that the 
  734.                      HiLite is to appear on the Top Line menu which would 
  735.                      highlight the title.
  736.  
  737.                      NameLen - For main menus, this is the length of the 
  738.                      HiLite that is to appear on the Top Line menu 
  739.                      highlighting the title.
  740.  
  741.                      CmdCol - For main menus, this is the column that the 
  742.                      CmdLtr appears on the Top Line menu which is highlighted.
  743.  
  744.                      Row .. Cols - These variables locate and size the window 
  745.                      for the menu.
  746.  
  747.                      DefaultLine - This is the line to be highlighted when the 
  748.                      program first starts.
  749.  
  750.                      HiLiteLine - This is the current position of the HiLite 
  751.                      on this menu.
  752.  
  753.                      SingleFlagLine - This is the line that has the only flag 
  754.                      in SingleChoice menu mode.
  755.  
  756.                      The following variables control the attributes in the 
  757.                      menus.  SameAttr is not permitted.
  758.  
  759.                        Battr - Border
  760.                        Wattr - entire Window contents
  761.                        Hattr - HiLite
  762.                        Lattr - command Letter
  763.                        Cattr - Comment line
  764.  
  765.                      Border - This is the border style used for the menu.
  766.  
  767.                      BackToDefault - If true, the HiLite will return to the 
  768.                      DefaultLine every time the menu is pulled down.  The 
  769.                      default is false.
  770.  
  771.  
  772.    Chapter 3, Data Structure                                           Page 13
  773.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  774.  
  775.  
  776.  
  777.                      Changed - PULL will toggle this to true if any of the 
  778.                      flags have been altered.  It is up to the programmer to 
  779.                      reset it to false if it is needed.
  780.  
  781.                      MsgLineNum - This is the index number of the MsgLine to 
  782.                      be displayed concurrently with this menu.
  783.  
  784.                      HelpWndwNum - This is the index number of the HelpWndw 
  785.                      record to be displayed for this menu when context-
  786.                      sensitive help is requested.
  787.  
  788.      MenuRecs      This array allocates the total number of main menu records 
  789.                    needed for the heap.  They do not all have to be used.
  790.  
  791.  
  792.    Variables - The following are the global variables used to create and 
  793.    control the pull-down menus:
  794.  
  795.      Variable      Description
  796.      ------------  -----------------------------------------------------------
  797.      MainMenu      (Type: ^MenuRecs) This is the pointer of the array of main 
  798.                    menu records in the heap.
  799.  
  800.      TopMenu       (Type: MenuRec)  As each menu record is accessed, main menu 
  801.                    or submenu, a copy of the record is made in TopMenu to 
  802.                    increase speed and save code.  The record is saved back in 
  803.                    the heap after use.
  804.  
  805.      MRI           (Type: word) (Menu Record Index)  When a menu is copied 
  806.                    into TopMenu, the array index of the record is saved in 
  807.                    this variable for later reference.
  808.  
  809.      LastMainMenu  (Type: byte)  This is the index of the last main menu 
  810.                    displayed on the far right of the Top Line menu.  It is 
  811.                    <=NumOfMainMenus.
  812.  
  813.      TopLineStr    (Type: CrtStrType)  This is the actual string that appears 
  814.                    as the Top Line menu when ShowTopLine is used.
  815.  
  816.      TopLineRow    (Type: byte) This is the row on which TopLineStr appears.
  817.  
  818.      MainMenuRow   (Type: byte) This is the row on which the top border of the 
  819.                    main menus appears.
  820.  
  821.  
  822.    Attributes - The following variables control the default attributes and 
  823.    border in all the main menus and the top line menu.  SameAttr is not 
  824.    permitted in byte types.
  825.  
  826.      Name           Type      Description
  827.      -------------  --------  -------------------------------------
  828.      InitAttr       integer   base screen, set by Attr in InitPull.
  829.      TopLineAttr    byte      top line menu.
  830.      TopLineHattr   byte      HiLite on top line menu.
  831.  
  832.  
  833.    Chapter 3, Data Structure                                           Page 14
  834.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  835.  
  836.  
  837.      TopLineLattr   byte      command Letters on top line menu.
  838.      MainMenuWattr  byte      entire Window contents.
  839.      MainMenuBattr  byte      main menu Border.
  840.      MainMenuHattr  byte      HiLite in main menu.
  841.      MainMenuLattr  byte      command Letters in main menu.
  842.      MainMenuCattr  byte      Comment line.
  843.      MainMenuBrdr   Borders   main menu Border style.
  844.  
  845.  
  846.    Keyboard - The following variables and constant contain the last keyboard 
  847.    input from ReadKbd or CheckForPullDown.
  848.  
  849.      Variable      Description
  850.      ------------  -----------------------------------------------------------
  851.      Key           (Type: char) Contains the key code of the input.
  852.  
  853.      ExtKey        (Type: boolean) Set true if extended key.
  854.  
  855.      WaitForKbd    (Type: boolean = true) This typed constant causes a wait 
  856.                    for keyboard input when executing CheckForPullDown.  If it 
  857.                    is false, then the current values of Key and ExtKey are 
  858.                    considered valid and execution continues.
  859.  
  860.  
  861.    Control Flags - The following variables programmably control the pull-down 
  862.    menus in lieu of the end user.
  863.  
  864.      Variable      Description
  865.      ------------  -----------------------------------------------------------
  866.      PullDown      (Type: boolean)  When set true, the menus will be pulled 
  867.                    down from their current position according to the sequence 
  868.                    in MoreCmdSeq.
  869.  
  870.      Pop           (Type: boolean)  This flag is controlled by CheckForPop and 
  871.                    sets it true if the program needs to pop out of the current 
  872.                    menu.
  873.  
  874.      PopToWorkWndw (Type: boolean)  If true, the menus will all pop and return 
  875.                    control to the work window.
  876.  
  877.      PopToTop      (Type: boolean)  If true, control is set to highlight the 
  878.                    Top Line menu.
  879.  
  880.      PopAndProcess (Type: boolean)  This flag is controlled by the Popped 
  881.                    function to execute a ProcPtr in the menus after all the 
  882.                    menus have been popped.
  883.  
  884.      PopLevels     (Type: byte)  This flag is controlled by SetCmdSeq or can 
  885.                    be used manually.  It simply pops the number of levels of 
  886.                    menus/windows.
  887.  
  888.      Quit          (Type: boolean = false)  This typed constant controls 
  889.                    execution of the program.  If set true, the program will 
  890.                    terminate with all menus popped.
  891.  
  892.  
  893.  
  894.    Chapter 3, Data Structure                                           Page 15
  895.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  896.  
  897.  
  898.  
  899.    Menu Sequence - The following variables indicate the current status of the 
  900.    menus and work windows.  You can know what the current menu is and the 
  901.    current sequence of letter commands to get there.
  902.  
  903.      Variable      Description
  904.      ------------  -----------------------------------------------------------
  905.      TopCmdLtrs    (Type: string[NumOfMainMenus])  This is the counterpart of 
  906.                    Menu.CmdLtrs for the Top Line menu.  It holds the command 
  907.                    letters for the Top Line menu where character 1 corresponds 
  908.                    to the first main menu, character 2 to the second, etc.
  909.  
  910.      CmdSeq        (Type: SeqStrType)  This is the current sequence of letters 
  911.                    used to arrive at the current menu/window where the last 
  912.                    character is the last menu.  While in the work window, this 
  913.                    string is null.  Do not change this string.
  914.  
  915.      MoreCmdSeq    (Type: SeqStrType)  When performing a programmed pull down, 
  916.                    this is the sequence of letters yet to be executed in the 
  917.                    same order as CmdSeq.
  918.  
  919.      MPulled       (Type: byte)  This is the index of the current main menu 
  920.                    pulled.
  921.  
  922.      SPulled       (Type: byte)  This is the index of the current submenu 
  923.                    pulled.  If no submenu is pulled, this value is 0.
  924.  
  925.      HiLited       (Type: byte)  This is the row number of the currently 
  926.                    highlighted line.
  927.  
  928.      AccessedWorkWndw  (Type: boolean)  This is a handy flag available for 
  929.                    testing in your program.  If you are in the menus and you 
  930.                    run your custom routine with ProcPtr to set this false, the 
  931.                    next time the work window is accessed, this variable will 
  932.                    be true.
  933.  
  934.      AccessedMenus (Type: boolean)  This is a handy flag available for 
  935.                    testing in your program.  If you are in the work window and 
  936.                    set this false, the next time the menus are accessed, this 
  937.                    variable will be true.
  938.  
  939.      WorkWndwStep  (Type: byte)  This is the current step number assigned to 
  940.                    the work windows in PULLWORK.PAS.
  941.  
  942.      TopWorkWndwName (Type: WindowNames)  This is the name of the work window 
  943.                    to be selected for access or the current one on top.
  944.  
  945.      InWorkWndw    (Type: boolean = true)  When true, this typed constant 
  946.                    indicates if the program is in the work window.  It is 
  947.                    otherwise in the menus.
  948.  
  949.  
  950.    Addresses for Calls - The following procedure pointers are used indirectly 
  951.    by calls in PULL.TPU using the procedure type.
  952.  
  953.  
  954.  
  955.    Chapter 3, Data Structure                                           Page 16
  956.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  957.  
  958.  
  959.      Procedure variable    Unit.Procedure
  960.      --------------------  -------------------------
  961.      CallGetUserPullStats  PullStat.GetUserPullStats
  962.      CallGetOverrideStats  PullStat.GetOverrideStats
  963.      CallWorkWndw          PullWork.WorkWndw
  964.      CallCheckGlobalKeys   PullStat.CheckGlobalKeys
  965.      CallKbdIdle           PullWork.KbdIdle
  966.  
  967.  
  968.    Untyped Key Constants - Several key constants have already been provided 
  969.    for frequently used keys.  Please refer to P70-VAR.INC for the listing.
  970.  
  971.  
  972.    SUBMENU DECLARATIONS
  973.  
  974.    The following type and variables are used for the sub menus.  The variables 
  975.    are described in the order of their appearance in the file P70-VAR.INC.  
  976.    The program was carefully planned so that main menu records would match 
  977.    that of the submenus.
  978.  
  979.  
  980.    Type - This type is used to structure variables in the heap for the 
  981.    submenus:
  982.  
  983.      Type          Description
  984.      ------------  -----------------------------------------------------------
  985.      SubMenus      This array allocates the total number of submenu records 
  986.                    needed for the heap.  They do not all have to be used.
  987.  
  988.    The Row/Col fields in the menu record for submenus default to zero so that 
  989.    PULL can locate them at run time for the slide-up configuration.  If they 
  990.    are set to non-zero values in PULLSTAT, then the menu will be located 
  991.    absolutely to the screen at (Row,Col).
  992.  
  993.    Variables - The following are the global variables used to allocate and 
  994.    configure the submenus:
  995.  
  996.      Variable      Description
  997.      ------------  -----------------------------------------------------------
  998.      SubMenu       (Type: ^MenuRecs) This is the pointer of the array of 
  999.                    submenu menu records in the heap.
  1000.  
  1001.      LastSubMenu   (Type: byte)  This is the index of the highest submenu 
  1002.                    record number in use.  It is <=NumOfSubMenus.
  1003.  
  1004.  
  1005.    Attributes - The following variables control the default attributes and 
  1006.    border in all the submenus.  SameAttr is not permitted in byte types.
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.    Chapter 3, Data Structure                                           Page 17
  1017.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1018.  
  1019.  
  1020.      Name          Type      Description
  1021.      ------------  --------  -------------------------------------
  1022.      SubMenuWattr  byte      entire Window contents.
  1023.      SubMenuBattr  byte      submenu Border.
  1024.      SubMenuHattr  byte      HiLite in submenu.
  1025.      SubMenuLattr  byte      command Letters in submenu.
  1026.      SubMenuCattr  byte      Comment line.
  1027.      SubMenuBrdr   Borders   submenu Border style.
  1028.  
  1029.  
  1030.    MESSAGE LINE DECLARATIONS
  1031.  
  1032.    The following type, constant and variables are used to generate normal key 
  1033.    messages or error messages on the message line.  
  1034.  
  1035.    Type - The following type is the only one needed for error messages:
  1036.  
  1037.      Type           Description
  1038.      -------------  -----------------------------------------------------------
  1039.      ErrMsgStrType  This is the type used to size the length for all error 
  1040.                     messages based on ErrMsgSize.  Since they are usually 
  1041.                     short, they can be trimmed to the length of the longest 
  1042.                     one.
  1043.  
  1044.    Constants - The following constants are given initial values to process the 
  1045.    messages on the message line.
  1046.  
  1047.      Constant           Description
  1048.      -----------------  ------------------------------------------------------
  1049.      CurrentMsgLineNum  (Type: word = 0)  This is the index of the current 
  1050.                         MsgLine displayed on the screen.
  1051.  
  1052.      EnableKeyStatus    (Type: boolean = true)  When true, the status of 
  1053.                         NumLock, ScollLock, and CapsLock will appear on the 
  1054.                         message line.
  1055.  
  1056.    Variables - The following variables allocate space for the messages in 
  1057.    global data and control the location of the messages and the key status 
  1058.    indicators:
  1059.  
  1060.      Variable      Description
  1061.      ------------  -----------------------------------------------------------
  1062.      MsgLine       (Type: array of CrtStrType)  This array allocates global 
  1063.                    data space for the messages.  If you intend to have several 
  1064.                    messages, you should consider making this data in the heap.
  1065.  
  1066.      ErrMsgLine    (Type: array of ErrMsgStrType)  This array allocates global 
  1067.                    data space for the error messages.  If you intend to have 
  1068.                    several messages, you should consider making this data in 
  1069.                    the heap.
  1070.  
  1071.      MsgLineRow    (Type: byte) This is the absolute row on which all messages 
  1072.                    and error messages are to appear. 
  1073.  
  1074.      CapsLockCol   (Type: byte) This is the column on the message line row on 
  1075.  
  1076.  
  1077.    Chapter 3, Data Structure                                           Page 18
  1078.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1079.  
  1080.  
  1081.                    which the status indicators will appear.
  1082.  
  1083.    Attributes - The following variables control the attributes on the message 
  1084.    line.  SameAttr is not permitted in byte types.
  1085.  
  1086.      Name           Type  Description
  1087.      ------------   ----  -----------------------------------------
  1088.      ErrMsgAttr     byte  For error messages.
  1089.      KeyStatusAttr  byte  For the key status indicators.
  1090.      MsgLineAttr    byte  For the normal messages.
  1091.      MsgLineHattr   byte  For the normal message highlight of keys.
  1092.  
  1093.  
  1094.    HELP WINDOW DECLARATIONS
  1095.  
  1096.    The following types and variables are used to create context-sensitive help 
  1097.    windows.  
  1098.  
  1099.    Type - The following record is the only one needed for help windows:
  1100.  
  1101.      Type          Description
  1102.      ------------  -----------------------------------------------------------
  1103.      HelpWndwRec   This record is used to fully describe any help window.  
  1104.                    Each field is described below:
  1105.  
  1106.                      FirstLine/LastLine - This is the first and last indexes 
  1107.                      in the HelpLines array that has the messages to appear in 
  1108.                      the help window.
  1109.  
  1110.                      LinesToShow - For now, the help window is a single page 
  1111.                      display and so this value is simply the number of lines 
  1112.                      from FirstLine to LastLine.
  1113.  
  1114.                      Row .. Cols - These variables locate and size the help 
  1115.                      window.  HelpBottomRow and HelpCharsPerLine are used to 
  1116.                      calculate these values.
  1117.  
  1118.                      The following variables control the attributes in the 
  1119.                      menus.  SameAttr is not permitted.
  1120.  
  1121.                        Battr - Border set by HelpWndwBattr
  1122.                        Wattr - entire Window contents set by HelpWndwWattr
  1123.  
  1124.                      Border - This is the border style used around the window 
  1125.                      and set to HelpWndwBrdr by default.
  1126.  
  1127.                      HWmodes - This is the window modes used to create the 
  1128.                      window on the screen.  HelpWndwModes is used to set this 
  1129.                      value by default.
  1130.  
  1131.                      MsgLineNum - This is the index number of the MsgLine to 
  1132.                      be displayed concurrently with the help window and is set 
  1133.                      by default to HelpMsgLineNum.
  1134.  
  1135.    Variables - The following variables allocate space for the records and help 
  1136.  
  1137.  
  1138.    Chapter 3, Data Structure                                           Page 19
  1139.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1140.  
  1141.  
  1142.    lines in global data and control the location and appearance of the window:
  1143.  
  1144.      Variable        Description
  1145.      --------------  ---------------------------------------------------------
  1146.      HelpWndw        (Type: array of HelpWndwRec)  This array allocates global 
  1147.                      data space for the help windows.  If you intend to have 
  1148.                      several help window, you should consider making this data 
  1149.                      disk based.
  1150.  
  1151.      HelpLine        (Type: array of ErrMsgStrType)  This array allocates 
  1152.                      global data space for all the help lines.  If you intend 
  1153.                      to have several lines, you should consider making this 
  1154.                      data disk based.
  1155.  
  1156.      HelpBottomRow   (Type: byte)  This is the default row on which the bottom 
  1157.                      row of the help window is to appear.  This keeps help 
  1158.                      windows down lower.
  1159.  
  1160.      HelpWndwModes   (Type: byte)  This is the default used to set 
  1161.                      HelpWndw.HWmodes.  See WNDW.DOC for setting this 
  1162.                      variable.
  1163.  
  1164.      HelpMsgLineNum  (Type: byte)  This is the index of MsgLine for the 
  1165.                      message to appear concurrently with the help window.  The 
  1166.                      index HelpML has been reserved as the default, but new 
  1167.                      ones can be used as well.
  1168.  
  1169.    Attributes - The following variables control the default attributes and 
  1170.    border in all the submenus.  SameAttr is not permitted in byte types.
  1171.  
  1172.      Name           Type      Description
  1173.      -------------  --------  -------------------------------------
  1174.      HelpWndwWattr  byte      entire Window contents.
  1175.      HelpWndwBattr  byte      help window Border.
  1176.      HelpWndwBrdr   Borders   help window Border style.
  1177.  
  1178.  
  1179.    DATA WINDOW / ENTRY DECLARATIONS
  1180.  
  1181.    The following types, constants and variables are used to create data entry 
  1182.    windows and work window data entry fields.
  1183.  
  1184.  
  1185.    Types - The following types are used to structure the data window/entry 
  1186.    records:
  1187.  
  1188.      Type            Description
  1189.      --------------  ---------------------------------------------------------
  1190.      TypeOfDataType  This enumerated type is used to indicate the type of data 
  1191.                      being processed.  Although the identifier list is 
  1192.                      intuitive, here is the list indicating its corresponding 
  1193.                      type:
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.    Chapter 3, Data Structure                                           Page 20
  1200.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1201.  
  1202.  
  1203.                        Name       Type
  1204.                        ---------  ---------
  1205.                        Bytes      byte
  1206.                        Words      word
  1207.                        ShortInts  shortint
  1208.                        Integers   integer
  1209.                        LongInts   longint
  1210.                        Reals      real
  1211.                        UserNums   DataStrType
  1212.                        Chars      char
  1213.                        Strings    DataStrType
  1214.  
  1215.  
  1216.      SetNames        This enumerated type identifies character sets to be used 
  1217.                      for filtering each keystroke.  The names up to CharSet 
  1218.                      are reserved, but the list can be appended.
  1219.  
  1220.      EntrySetArray   This is the structure for allocating the data entry 
  1221.                      filter sets for the constant EntrySet.
  1222.  
  1223.      DataEntryRec    This record is used to fully describe any data entry.  
  1224.                      Each field is described below:
  1225.  
  1226.                        VarAddr - This is the absolute address where the 
  1227.                        contents of the entry is stored.
  1228.  
  1229.                        TypeOfData - This declares the type of data located at 
  1230.                        VarAddr.  It is up to your programming skills to make 
  1231.                        sure that VarAddr and TypeOfData agree.
  1232.  
  1233.                        Row .. Col - For data windows, if these values default 
  1234.                        to (1,2) for the field location.  For data entry, this 
  1235.                        is the window-relative location of the field.
  1236.  
  1237.                        Field - This is the number of columns designated for 
  1238.                        the input and output to be displayed.
  1239.  
  1240.                        MaxField - This is the maximum number of characters 
  1241.                        that can appear in a field.  They can be less than or 
  1242.                        greater than Field which creates a flex-field entry.  
  1243.                        For strings, be sure that MaxField is no longer than 
  1244.                        the string destination or DataStrSize.
  1245.  
  1246.                        Decimals - For reals, this value is used to format the 
  1247.                        output output display which is Real:Field:Decimals.  If 
  1248.                        Decimals is negative then the format is Real:Field.
  1249.  
  1250.                        SetName - This is the name of the set used to filter 
  1251.                        the keystrokes into the field.  This variable is set by 
  1252.                        default according to TypeOfData.
  1253.  
  1254.                        TranslateProc - This procedure pointer is used to 
  1255.                        execute a procedure to intercept the keystroke for 
  1256.                        translation.  The default is nil.
  1257.  
  1258.  
  1259.  
  1260.    Chapter 3, Data Structure                                           Page 21
  1261.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1262.  
  1263.  
  1264.                        CheckRangeProc - This procedure pointer is used to 
  1265.                        execute a procedure for checking the range or content 
  1266.                        of the entry before it is stored in the assigned 
  1267.                        variable.  The default is nil.
  1268.  
  1269.                        JustifyOutput - The justification of the output in data 
  1270.                        entry fields can be displayed by DisplayFields either 
  1271.                        right or left justified.  By default, numbers are right 
  1272.                        justified and strings left.
  1273.  
  1274.                        The following variables control the attributes in the 
  1275.                        menus.  SameAttr is not permitted.
  1276.  
  1277.                          Iattr - Input  default set by DataWndwIattr
  1278.                          Oattr - Output default set by DataWndwOattr
  1279.  
  1280.                        MsgLineNum - This is the index number of the MsgLine to 
  1281.                        be displayed concurrently with this entry during input.
  1282.  
  1283.                        HelpWndwNum - This is the index number of the HelpWndw 
  1284.                        record to be displayed when context-sensitive help is 
  1285.                        requested.
  1286.  
  1287.      DataWndwRec     This record is used to fully describe any data window.  
  1288.                      Each field is described below:
  1289.  
  1290.                        Title - This is the title to appear centered on the top 
  1291.                        row of the border.  The default is ''.
  1292.  
  1293.                        DWrow / DWcol - If these values are the default zero, 
  1294.                        PULL will locate the window at run time for the slide-
  1295.                        under configuration.  Non-zero values will override 
  1296.                        PULL and locate the window absolute to the screen.
  1297.  
  1298.                        Battr - This is the attribute of the data window 
  1299.                        border.
  1300.  
  1301.                        Border - This is the border style of the border.
  1302.  
  1303.                        Entry - (Type: DataEntryRec) This is a record within 
  1304.                        the DataWndwRec that fully describes the field inside 
  1305.                        the window.
  1306.  
  1307.      DataWndws       This sets the structure for all of the data window 
  1308.                      records to be allocated in the heap.
  1309.  
  1310.      DataEntries     This sets the structure for all of the data entry records 
  1311.                      in a work/user window to be allocated in the heap.
  1312.  
  1313.      DataStrType     Combined with DataStrSize, this type will limit the size 
  1314.                      of strings that can be entered/read from any data entry.
  1315.  
  1316.      DataPadRec      This record conveniently groups all of the data needed 
  1317.                      for the Data Pad.  Each one of the fields is described 
  1318.                      below.
  1319.  
  1320.  
  1321.    Chapter 3, Data Structure                                           Page 22
  1322.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1323.  
  1324.  
  1325.  
  1326.                        StoreMode - If true, the Data Pad will store the data 
  1327.                        to its destination variable, else the Data Pad reads 
  1328.                        the contents of the variable.
  1329.  
  1330.                        Valid - The result saved from the validity check for 
  1331.                        numbers is true if it passes.
  1332.  
  1333.                        DataStored - If the data passes the validity check, the 
  1334.                        range check, and is stored, this variable is set true 
  1335.                        which is later used to set TopMenu.Changed to true.
  1336.  
  1337.                        NewData - This flag is used internally to indicate an 
  1338.                        untampered entry has been displayed for editing.  Once 
  1339.                        edited, this value is false.
  1340.  
  1341.                        PullDW - This flag indicates that a pull-down data 
  1342.                        window is being used for data entry.
  1343.  
  1344.                        FieldIndex - This is the index of DataStr for the first 
  1345.                        character shown in the field.
  1346.  
  1347.                        CursorOfs - This is the offset from FieldIndex for the 
  1348.                        position of the cursor.
  1349.  
  1350.                        Hattr - The attribute for the HiLite used to move from 
  1351.                        field to field in the work window or user window can be 
  1352.                        any attribute.  If SameAttr is used, only the cursor is 
  1353.                        moved and the output attribute remains unchanged.
  1354.  
  1355.                        ErrMsg - After a range check, if this value is zero, 
  1356.                        the entry value is in range.  If not, it is the number 
  1357.                        of the error message to be displayed.
  1358.  
  1359.                        Flex - If MaxField does not equal Field, this value is 
  1360.                        set to 1 to indicate a flex field.
  1361.  
  1362.                        Justify - This indicates the type of justification for 
  1363.                        the input and output display of the field.  Input is 
  1364.                        always left, but output can either be left or right.
  1365.  
  1366.                        TypeOfDataType - The last field in the data pad is the 
  1367.                        scratch pad for placing any type of data.  To access 
  1368.                        the data, use one of the following variant field 
  1369.                        identifiers:
  1370.  
  1371.                          Identifier Type
  1372.                          ---------- ---------
  1373.                          Bdata      Bytes
  1374.                          Wdata      Words
  1375.                          SIdata     ShortInts
  1376.                          Idata      Integers
  1377.                          Ldata      LongInts
  1378.                          Rdata      Reals
  1379.                          UNdata     UserNums
  1380.  
  1381.  
  1382.    Chapter 3, Data Structure                                           Page 23
  1383.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1384.  
  1385.  
  1386.                          Cdata      Chars
  1387.                          Sdata      Strings
  1388.  
  1389.  
  1390.    Typed Constant - EntrySet is the array of the actual sets used for 
  1391.    filtering the keystrokes before being entered into the field.  Along with 
  1392.    each index name is the application of the set.  The sets up to CharSet are 
  1393.    reserved.  Other sets can be appended.
  1394.  
  1395.      Index name   Application
  1396.      -----------  -----------------------------------------
  1397.      UnsignedSet  For Bytes and Words
  1398.      SignedSet    For ShortInts, Integers, and LongInts
  1399.      RealSet      For Reals
  1400.      CharSet      For Chars, Strings and misc. entry
  1401.      HexSet       For UserNums and Hex
  1402.      FileNameSet  For DOS file names
  1403.      PathSet      For DOS full path file names
  1404.      MaskSet      For DOS full path file names with wildcard
  1405.  
  1406.    Variables - The following variables allocate space for data windows, data 
  1407.    entries, and the data pad: 
  1408.  
  1409.      Variable      Description
  1410.      ------------  ---------------------------------------------------------
  1411.      DWI           (Type: word)  Data Window Index used to save the current 
  1412.                    data window record number currently in TopDataWndw.
  1413.  
  1414.      DEI           (Type: word)  Data Entry Index used to save the current 
  1415.                    data entry record number currently in TopEntry.
  1416.  
  1417.      TopDataWndw   (Type: DataWndwRec)  This is a copy of the record from the 
  1418.                    heap of the current DataWndwRec.  This saves code.
  1419.  
  1420.      TopEntry      (Type: DataEntryRec)  This is a copy of the record from the 
  1421.                    heap of the current DataEntryRec.  This saves code.
  1422.  
  1423.      DataWndw      (Type: ^DataWndws) This pointer accesses the array of 
  1424.                    data window records in the heap.
  1425.  
  1426.      DataEntry     (Type: ^DataEntry) This pointer accesses the array of 
  1427.                    data entry records in the heap.
  1428.  
  1429.      DataStr       (Type: DataStrType)  This is the actual string edited on 
  1430.                    the screen during an entry into a field.  The length of the 
  1431.                    string is limited by DataStrSize.
  1432.  
  1433.      DataStrL      (Type: byte)  This is the current string length of DataStr 
  1434.                    by accessing DataStr[0].
  1435.  
  1436.      DataPad       (Type: DataPadRec)  This is the data pad used to transfer 
  1437.                    data between the destination variable and the screen.
  1438.  
  1439.      AutoTab       (Type: boolean)  When set true for EnterSeq, the HiLite 
  1440.                    will advance to the next field automatically after entry.
  1441.  
  1442.  
  1443.    Chapter 3, Data Structure                                           Page 24
  1444.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1445.  
  1446.  
  1447.  
  1448.      AutoNumLock   (Type: boolean)  For numerical entries, this flag will 
  1449.                    automatically turn on NumLock and is shown on the message 
  1450.                    line with the key status indicator.
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.    Chapter 3, Data Structure                                           Page 25
  1505.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1506.  
  1507.  
  1508.    A P P E N D I X  A :   M E M O R Y   A L L O C A T I O N
  1509.  
  1510.    This section covers the memory requirements for global data in the data 
  1511.    segment and dynamic data in the heap.  This will give you the figures on 
  1512.    how to estimate the memory needed for your program.
  1513.  
  1514.  
  1515.    CHOOSING GLOBAL VS. DYNAMIC
  1516.  
  1517.    As is, PULL uses both global and dynamic memory for records and messages.  
  1518.    The menus and data window/entry records are dynamic while the help window 
  1519.    and messages use global memory.  Depending on the needs of your application 
  1520.    program, you can change where these records are located by removing or 
  1521.    adding the ^ symbol, if you have the source code, along with the usual 
  1522.    HeapOK/GetMem instructions.
  1523.  
  1524.    PULLDEMO - In the demonstration, it was chosen to use the messages and help 
  1525.    windows as global memory since the program was so small.  In larger 
  1526.    programs that need more global data, these records can be shifted to 
  1527.    dynamic memory or even to disk.
  1528.  
  1529.  
  1530.    GLOBAL MEMORY
  1531.  
  1532.    Global Memory - The following values reflect both the approximate minimum 
  1533.    data requirements when global memory is a premium, and the allocation used 
  1534.    in PULL.TPU using the current configuration constants.  These values may 
  1535.    vary slightly.
  1536.  
  1537.                                      Min    Demo
  1538.      Features                        Bytes  Bytes  Comments
  1539.      ------------------------------- -----  -----  -------------------
  1540.      Basic pull-down menus             652    652
  1541.      Submenus                           12     12
  1542.      Data window/entry, filter sets    579    675 
  1543.      Help windows                       34   4611  Used global in demo
  1544.      Messages                           16   1326  Used global in demo
  1545.                                      -----  -----
  1546.      Total allocation                 1293   7276
  1547.  
  1548.    Of course your application will vary, but these figures give you a good 
  1549.    estimate of the amount of memory being used.  The demo figures for the help 
  1550.    windows and message are higher because the text strings were placed in 
  1551.    global memory.
  1552.  
  1553.  
  1554.    DYNAMIC MEMORY
  1555.  
  1556.    Dynamic Variables - To alleviate using global data, dynamic variables are 
  1557.    used for permanent and temporary use.  The allocation for menus and data 
  1558.    window/entry records are permanent throughout the program.  Many other 
  1559.    procedures such as pulling down menus temporarily use the heap to perform 
  1560.    operations. 
  1561.  
  1562.    Permanent Variables - If the directives have been defined, the following 
  1563.  
  1564.  
  1565.    Appendix A: Memory Allocation                                       Page 26
  1566.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1567.  
  1568.  
  1569.    allocation can be calculated:
  1570.  
  1571.      Records       Calculation                                     Demo Bytes
  1572.      ------------  ----------------------------------------------  ----------
  1573.      Menus         SizeOf(TopMenu)*(NumOfMainMenus+NumOfSubMenus)   7664
  1574.      Data windows  SizeOf(TopDataWndw)*(NumOfDataWndws)              658
  1575.      Data entries  SizeOf(TopEntry)*(NumOfDataEntries)               240
  1576.  
  1577.    Again, this is just a general idea of what your program would allocate.  
  1578.    This is totally dependent on the configuration constants you choose.
  1579.  
  1580.    Temporary Variables - When pulling down menus, the underlays are accessed 
  1581.    in a serial fashion, so your calculations can be exact.  There is no need 
  1582.    to double the size of the heap needed as you would for random access.  For 
  1583.    a further discussion on dynamic memory allocation for windows, please refer 
  1584.    to the appendix in WNDWREF.DOC.
  1585.  
  1586.  
  1587.    CODE SIZE
  1588.  
  1589.    Code Size - PULL is also very frugal with with code.  Here is the 
  1590.    breakdown for code usage (this may vary slightly):
  1591.  
  1592.      Code Description                Bytes
  1593.      ------------------------------- -----
  1594.      Basic pull-down menus            4773
  1595.      Additional for submenus          1292
  1596.      Additional for data wndw/entry   3979
  1597.      Additional for help windows       616
  1598.      Additional for messages          1109
  1599.                                      -----
  1600.      Total code                      11769
  1601.  
  1602.    The code size will be a few hundred bytes less if you use SpeedPack II Strg 
  1603.    unit.  Of course the smart compiler will optimize the code leaving out 
  1604.    unused procedures.  But this gives you a good idea of how small the code 
  1605.    really is!
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.    Appendix A: Memory Allocation                                       Page 27
  1627.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 7.0a
  1628.  
  1629.  
  1630.    A P P E N D I X  B :   E R R O R   M E S S A G E S
  1631.  
  1632.    PULL uses the same GOOF unit as WNDW does.  Should you make a mistake in 
  1633.    programming with windows or PULL,  the program will terminate with an error 
  1634.    message window on the CRT to reveal any problem.  The program terminates 
  1635.    through the GOOF unit which can be freely edited.
  1636.  
  1637.  
  1638.    WNDW
  1639.  
  1640.    The following error messages occur when a mistake has been made in creating 
  1641.    or controlling windows:
  1642.  
  1643.    "Not enough heap space" - The minimum heap size is too small.  Increase the 
  1644.    size as required in APPENDIX A of WNDW70C.DOC.
  1645.  
  1646.    "Too many windows" - Tried to create more windows than MaxWndw allows.  
  1647.    Either remove windows or increase MaxWndw.
  1648.  
  1649.    "Too many virtual windows" - Tried to create more virtual windows than 
  1650.    MaxVirtualWndw allows.  Either remove windows or increase MaxVirtualWndw.
  1651.  
  1652.    "Perm window out of order" - Tried to create a PermMode window while a 
  1653.    normal window is the top window.  Remove or hide window before making a 
  1654.    permanent window.  Routinely, all PermMode windows are created first.
  1655.  
  1656.    "No window to remove" - Tried to remove the initial window Window0 which is 
  1657.    permanent.
  1658.  
  1659.    "Hidden window not found" - Tried to write to a hidden window that does not 
  1660.    exist.  Check for the correct name.
  1661.  
  1662.    "Virtual screen not found" - Tried to write to a virtual screen that does 
  1663.    not exist.  Check for the correct name.
  1664.  
  1665.    "Video page not available" - Tried to write to a video page that has not 
  1666.    been allocated or does not exist for the hardware as expected.  Be sure to 
  1667.    use MaxValidPage.
  1668.  
  1669.  
  1670.    PULL
  1671.  
  1672.    Only the following additional error message will occur because of PULL:
  1673.  
  1674.    "A Submenu could not fit" - Tried to fit a menu that was too wide to fit in 
  1675.    the slide-up configuration.  Set LocationWarning false and test all 
  1676.    submenus to see if the slide-under alternative is acceptable.  If not, 
  1677.    override the default location by manually assigning the Row and Col values 
  1678.    of the menu record in GetUserPullStats.
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.    Appendix B: Error Messages                                          Page 28
  1688.